---
sidebar_position: 3
sidebar_label: Migrating from Terraform 1.8.x
description: |-
    Learn how to migrate to OpenTofu from Terraform.
---

# Migrating to OpenTofu from Terraform 1.8.x

When migrating from Terraform 1.8.x, please migrate to OpenTofu 1.8.2 first, then
[upgrade your OpenTofu installation](/docs/intro/upgrading/) to the latest version.

OpenTofu 1.8.2 is largely compatible with Terraform 1.8.x with a few minor changes needed. This migration guide will
take you through the process of switching from Terraform to OpenTofu.

## Step 0: Prepare a disaster recovery plan

Although OpenTofu 1.8.2 is very similar to Terraform 1.8.2, make sure you have an up to date and *tested* disaster
recovery plan.

## Step 1: Upgrading Terraform

This migration guide is only valid for Terraform 1.8.2. If you are on a Terraform version below 1.8.2, please upgrade
to at least Terraform version 1.8.2 before proceeding with the migration by following the
[Terraform upgrade guide](https://developer.hashicorp.com/terraform/language/v1.8.x/upgrade-guides). If you are on a
higher Terraform version, please wait until an appropriate migration guide becomes available.

## Step 2: Apply all changes with Terraform

Before proceeding, make sure that you apply all changes with `terraform apply`. Running `terraform plan` should result
in no planned changes. While you can switch to OpenTofu with pending changes, it is not recommended.

```
$ terraform plan

...

No changes. Your infrastructure matches the configuration.

Terraform has compared your real infrastructure against your
configuration and found no differences, so no changes are needed.
```

## Step 3: Install OpenTofu 1.8.2

As a first step, please [follow the installation instructions for the OpenTofu CLI tool](intro/install/index.mdx). Please test
if you can successfully execute the `tofu` command:

```
$ tofu --version
OpenTofu v1.8.2
on linux_amd64
```

## Step 4: Back up your state file and code

Before you begin using the `tofu` binary on your Terraform code, make sure to back up your state file. If you are using
a local state file, you can simply make a copy of your `terraform.tfstate` file in your project directory.

If you are using a remote backend such as an S3 bucket, make sure that you follow the backup procedures for the
backend and that you exercise the restore procedure at least once.

Additionally, make sure you back up or version your code as the migration will require some code changes.

## Step 5: Code changes

For a successful migration, you will need to perform the following code changes

### Functions

The following functions are not supported in OpenTofu:

- `encode_tfvars`
- `decode_tfvars`
- `encode_expr`

If you rely on these functions, please refactor your code to work without them.

### S3 backend

If you are using the S3 backend, please change your code as follows:

1. If you are using the `skip_s3_checksum` option on the S3 backend, OpenTofu recommends removing it if the used S3 compatible API can work with SHA256 checksum validation.
2. If you are using the `endpoints` &rarr; `sso` option or the `AWS_ENDPOINT_URL` environment variable, remove this option and verify if your code still works as intended after the migration.

### Removed block

The OpenTofu `removed` block works differently from the Terraform variant. Please [review the documentation](../../language/resources/syntax.mdx#removing-resources) and make the following changes:

1. Remove the `lifecycle` block. If you used the `lifecycle` &rarr; `destroy = true` setting, remove the entire `removed` block. Verify that the code still works as intended after the migration.

### Testing changes

If you are using the `terraform test` feature, you will need to perform the following changes:

1. If you are using `override_resource` or `override_data` nested in a `mock_provider` restructure your tests to work without these features (see [OpenTofu issue #1204](https://github.com/opentofu/opentofu/issues/1204)).

## Step 6: Initialize OpenTofu

:::warning

Should any of the following steps fail, please do not proceed and follow the
[rollback instructions below](#rolling-back-to-terraform-and-reporting-issues) instead.
If you suspect the failure may be the result of a bug in OpenTofu,
[please help us by opening an issue](https://github.com/opentofu/opentofu/issues).

:::

Now you are ready to migrate. Run `tofu init` in the directory where your Terraform code resides. OpenTofu will download
any providers and modules referenced in your configuration from the OpenTofu registry.

## Step 7: Inspect the plan

Once initialized, run `tofu plan` and ensure that there are no pending changes similar to step 1 above. If there are
unexpected changes in the plan, roll back to Terraform and troubleshoot your migration. (See the Troubleshooting section
below.)

```
$ tofu plan

...

No changes. Your infrastructure matches the configuration.

OpenTofu has compared your real infrastructure against your
configuration and found no differences, so no changes are needed.
```

## Step 8: Apply

Even though there should be no changes in your infrastructure, you should run `tofu apply` to ensure that OpenTofu
updates the state file.

## Step 9: Test out a small change

Before you begin using OpenTofu for larger changes, test out `tofu apply` with a smaller, non-critical
change.

## Step 10: Upgrade to the latest OpenTofu version

Now that the migration is complete, follow the [upgrade guide](/docs/intro/upgrading/) for OpenTofu to upgrade to the
latest version.

## Rolling back to Terraform and reporting issues

If you have issues migrating to OpenTofu you can follow these steps to roll back to Terraform:

1. Create another backup of your state file and code.
2. Remove any code changes you have made.
3. Run `terraform init`.
4. Run `terraform plan` and verify that no unexpected changes are in the plan.
5. Run `terraform apply` and verify that it runs properly with no changes.
6. Test the rollback with a small, non-critical change.

If you encountered a bug, [please report it on GitHub](https://github.com/opentofu/opentofu/issues).

## Troubleshooting

If you encounter any issues during the migration to OpenTofu, you can join the <a href="/slack/">OpenTofu Slack</a> or ask on
[GitHub Discussions](https://github.com/orgs/opentofu/discussions).

### Error: Failed to query available provider packages

This error happens when a provider you specified in your configuration is not available in the OpenTofu registry.
Please roll back to Terraform and make sure your code works with Terraform. If your code works, please
[submit an issue to include the provider in the registry](https://github.com/opentofu/registry/issues/).

### Error: Module not found

This error happens when a module you specified in your configuration is not available in the OpenTofu registry.
Please roll back to Terraform and make sure your code works with Terraform. If your code works, please
[submit an issue to include the module in the registry](https://github.com/opentofu/registry/issues/).
